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Argv Debug Library 

The argv library has been designed to handle the argument processing needs of most 
Unix software and to provide a consistent usage framework for user applications. 

The module is reasonably portable having been successfully run on the following operat- 
ing systems: ESDI, SunOS, Solaris, AIX, Ultrix, OSF, Irix, HPUX, MS-DOG, and probably 
a couple others. 

The package includes the library, configuration scripts, shell-script utility application, 
test program, and extensive documentation (text, texi, info, ps). 

The library is available via ftp from ‘ftp.letters.com’ in the ‘/src/argv‘ directory. 
See Section 2.2 [How To Get], page 3. I can be reached at ‘gray@letters.com’ with any 
questions, feedback, or general comments. 
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1 Library Copying Conditions 

Copyright © 1992 to 1997 by Gray Watson. 

Gray Watson makes no representations about the suitability of the software described 
herein for any purpose. It is provided “as is” without express or implied warranty. The 
name of Gray Watson cannot be used in advertising or publicity pertaining to distribution 
of the document or software without specific, written prior permission. 

Permission to use, copy, modify, and distribute this software for any purpose and without 
fee is hereby granted, provided that the above copyright notice and this permission notice 
appear in all copies, and that the name of Gray Watson not be used in advertising or 
publicity pertaining to distribution of the document or software without specific, written 
prior permission. 

Gray Watson makes no representations about the suitability of the software described 
herein for any purpose. It is provided "as is" without express or implied warranty. 
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2 How to Use the Library 


2.1 The General Concepts Behind the Library 

One thing that almost all Unix executables need to do is process the command line 
arguments. Whether this is to enable verbose mode or specify the files for a utility to work 
on, code has to be written to process these user specified options. 

int main(int argc, char **argv) 

{ 

} 

As you must know, the command line arguments in most Unix systems are passed in 
as arguments to main() (seen above). The argc integer argument contains the number of 
arguments specified. The argv variable holds the arguments themselves. It can be thought 
of as a pointer to a list of character pointers - or an array of character pointers. 

To get a particular argument from argv, you use argv [x] where x is an integer whose 
value is from 0 to argc - 1. In most Unix implementations, the zeroth argument is always 
the name the program was executed with. For instance, if you typed ‘./Is -al’, argc 
would equal 2 and the value of argv[0] would be ./Is"’. The value for argv[l] would 
be ‘"-al"’. 

Currently, most programmers either write code on a per program basis to process argu- 
ments or they use the getoptO routine. Writing argument processing code for each pro- 
gram results in improper and inconsistent argument handling. Although better, getoptO 
does not provide the structure needed to ensure conformity in argument processing and still 
requires significant code to be written by the programmer. 

The goal for this library was to achieve a standardized way of processing arguments - 
especially in terms of error and usage messages. Important consideration was also given to 
reducing the programming time necessary to enable the functionality. 


2.2 How to get the library. 

The newest versions of the argv library are available via anonymous ftp from ‘ftp . letters . com’| 
in the ‘/src/argv’ directory. 

To use anonymous ftp, you ftp to the site and when the system prompts you for a login- 
id or username you enter anonymous. When it prompts you for a password you enter your 
email address. I, for example, enter gray@letters.com. You then can change-directory 
(cd) into ‘/src/argv’ and get the ‘README’ and ‘argv. tar .gz’ files. 

The versions in this repository also include such files as a postscript version of the manual 
and other large files which may not have been included in the distribution you received. 
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2.3 Installing the Library 

To configure, compile, and install the library, follow these steps carefully. 

1. Type sh . /configure to configure the library. You may want to first examine the 
‘conf ig.help’ file for some information about configure. Configure should generate 
the ‘Makefile’ and some configuration files automatically. 

NOTE: It seems that some versions of tr (especially from HP-UX) don’t understand 
tr ’ [a-z] ’ ’ [A-Z] ’ . Since configure uses tr often, you may need to either get GNU’s 
tr (in their textutils package) or generate the ‘Makefile’ and ‘conf .h’ files by hand. 

2. You may want to examine the ‘Makefile’ and ‘conf .h’ files created by configure to 
make sure it did its job correctly. 

3. Typing make should be enough to build ‘libargv.a’ and the ‘argv_shell’ utility. If 
it does not work, please send me some notes so future users can profit from your 
experiences. 

NOTE: The code is pretty dependent on a good ANSI-C compiler. If the configure 
script gives the ‘WARNING’ that you do not have an ANSI-C compiler, you may still 
be able to add some sort of option to your compiler to make it ANSI. If there such 
is an option, please send it to the author so it can be added to the configure script. 
Otherwise, you will have to try make noansi. This will run the ‘Deansify.pl’ perl 
script on the code which: 

• WARNING: modifies the source code in place 

• changes all void * references to char *. 

• fixes all functions to remove foo(char * var) declarations. 

If it doesn’t work you may have to do Deansify.pl’s job by hand. 

4. Typing make tests should build the ‘argv_t’ test program. This can be run and given 
arguments to test the various library features. 

5. Typing make install should install the ‘libargv.a’ library in ‘/usr/local/lib’, the 
‘argv_shell’ utility in ‘/usr/local/bin’, and the ‘argv.info' documentation file in 
‘/usr/local/inf o’. 

You may have specified a ‘ — pref ix=PATH’ option to configure in which can ‘/usr/local’| 
will have been replaced with ‘PATH’. 

See the Getting Started section to get up and running with the library. See Section 2.4 
[Getting Started], page 4. 

2.4 Getting Started with the Library 

This section should give you a quick idea on how to get going. 

1. Follow the installation instructions on how to configure and make and install the library 
(i.e. type: make install). See Section 2.3 [Installation], page 4. 

2. Examine the ‘argv_t . c’ test program source to see an example of how to program with 
the library. After adding the appropriate argv_t structure array to your main source 
file, you need to compile and link your programs with the library. 
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3. The first time your program is run, the library makes a number of checks as to the 
validity of the argument structures being used. You may have to note and fix reported 
problems. 

4. Run your program with the ‘ — usage’ argument and voila. 
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3 The Library’s Operations 

3.1 The argv_t Structure and It’s Usage 

The argv_t argument structure is as follows: 
typedef struct { 


char 

ar _ short _arg; 

/* short argument */ 

char 

*ar_long_arg; 

/* long argument */ 

short 

ar_type ; 

/* type of variable */ 

void 

*ar_variable ; 

/* point to variable to set */ 

char 

*ar_var_label ; 

/* label for var description */ 

char 

*ar_help_label ; 

/* help lable for the arg */ 


> argv_t ; 

The ar_short_arg element contains the character value of the short option (’d’ for ‘-d’) 
or special codes such as ARGV_LAST which identifies the last element in the array. See 
Section 3.2 [Special Short Args], page 6. 

The ar_long_arg element (if not-NULL) holds the string which is the long version of 
ar_ short _arg. For instance, with ‘ — d’ , you might have "delete". This would mean that 
‘-d’ and ‘ — delete’ would be equivalent. ‘ — ’ is the long-option prefix per POSIX specs. 

You would define an array of these arguments at the top of the file with main() in it. 
static char copy = ARGV_FALSE; 

static argv_t args [] = { 

{ ’c\ "copy", ARGV_B00L, &copy, NULL, "copy-files flag" >, 

{ ’g’, "group", ARGV_CHARP, &group, "group", "name of group to set" }, 

{ ARGV_LAST } 

>; 


int main(int argc, char ** argv) 

{ 

argv_pr o c e s s ( args , ar gc , argv ) ; 

> 

3.2 The Special ar_short_arg Values 

There are 3 types of arguments: 

optional Arguments that may or may not be supplied by the user. 
mandatory 

Arguments that must be supplied by the user. For instance grep must be given 
an expression on the command line. 

If the argument is a mandatory argument which has no -%c prefix then the 
ar_short_arg element should be assigned ARGV_MAND. 
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maybe Arguments that might be specified by the caller but are not mandatory. For 
instance, you can grep a file or you can grep standard-input. The file should be 
a maybe argument. 

If this is a maybe argument then use ARGV-MAYBE in the ar_short_arg 
field. 

To mark the last entry in the structure list use ARGV_LAST. ARGV_OR also works. 

3.3 The argv_t Structure and It’s Usage 

Ar_type holds the type of the argument whether an optional argument or mandatory. 
Below are the available values for this field. 

ARGV_B00L 

boolean type, sets the variable to ARGV_TRUE if used 

ARGV_B00L_NEG 

like the boolean type but sets the variable to ARGV-FALSE if used 

ARGV_CHAR 

a single character 

ARGV_CHARP 

a string of characters (character pointer) 

ARGV.FLOAT 

a floating pointer number 
ARGV_INT an integer number 
ARGV_L0NG 

a long integer number 

ARGV_BIN a binary base-2 number (Os and Is) 

ARGV_0CT an octal base-8 number (0 to 7) 

ARGV_HEX a hexadecimal base-16 number (0 to 9 and A to F) 

ARGV_INCR 

a integer type which is incremented each time it is specified 

For printing out of the type of the argument on the command line, use the ‘ — argv-di splay ! | 
option which will display the argument, its type and value. It will display the variables’ 
default values if no arguments specified before it on the command line otherwise it will 
show the values the variables are set to after processing the arguments. 

Basically the argument processing routines, examine the type of the variable, absorb 
another argument (if necessary), and then translate the string argument (if necessary) and 
write the data into the address stored in the ar_variable field. 

ARGY-BOOL, ARGV_BOOL_NEG, and ARGVJNCR are special in the above list in 
that they do not require another argument. With ‘Is -1’, for example, the ‘-1’ flag lives on 
its own. With ‘install -m 444 . . .’, on the other hand, ‘444’ is an octal number argument 
associated with ‘-m’ and will be translated and assigned to the ‘-m’ mode variable. 
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Needs to be written. Sorry. 
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4 Invoking Programs Which Use the Library 

4.1 How to get usage messages from argv programs 

If a program ‘install’ has the library compiled in you should be able to do a ‘install 
— usage-long’ to get the long-format usage message. 

Usage: install 

[— c] or — copy-files = copy file(s), don't move °/ 0 t 

[-g group] or — group-id = group id name (default bin) °/ 0 s| 

[-m octal-mode] or — mode-value = permissions mode value ‘/„o 

[-o owner] or — owner-id = owner id name (default bin) °/ 0 s| 

[-s] or — strip = strip destination binary °/ 0 t 

[file(s)] directory/destination = files to install or mkdir arg| 

In the above example, the program install’s usage message is detailed. The ‘ [-c] ’ line 
details the copy-files flag. You can either enable it with a ‘— c’ or ‘ — copy-files’. The 
description of the flag follows with lastly, a ‘%t ’ showing that it is a true/false flag. 

The ‘ [-g] ’ line shows the group-id flag. It is different from the ‘— c’ flag since, if used, 
it takes a group string argument (notice the ‘°/ 0 s’ at the end of the line indicating it takes a 
string argument). 

‘install — usage-short’ or just ‘ — usage’ will get you a condensed usage message: 

Usage: install [-cs] [-g group] [-m octal -mode] [-o owner] [file(s)] 
directory/destination 

4.2 How to Specify Arguments to Argv Programs 

Specifying arguments to a program which uses the library is quite straight-forward and 
standardized. Once you have learned how to do it once, you can use any program with it. 

There are five basic types of arguments as defined by the library: 
true/false flags 

Do not have an associated value and the program will get a True if one is 
specified else False. 

The ‘ — c ’ in ‘install -c’. 
varia ble flags 

Have an associate value which will be supplied to the program. 

The ‘-m’ in ‘install -m 0644’ will get the value ‘0644’. 
values Arguments without a ‘-’ and are associated values for the variable flags. 
mandatory 

Arguments without a but are not associated to variable flags. These can be 
supplied to the program if allowed. They are mandatory in that they must be 
supplied. If the program asks for 3 arguments, 3 must be supplied. NOTE that 
order is important with these. 

The ‘from’ and ‘to’ arguments in ‘install from to’. 
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maybe These are the same as the mandatory arguments except they are optional ar- 
guments and can but do not have to be supplied. 

The ‘file’ argument in ‘Is file’ since ‘Is’ does not require a file to be listed 
to work. 

The values for the variable flags are assigned in a straight First-In-First-Out queue. In 
‘install -m -g 0644 bin’, the value ‘0644’ is assigned to the ‘-m ! flag and the value ‘bin’ 
is assigned to ‘-g’. 

Additional values that cannot be matched to variable flags will become mandatory or 
maybe arguments if the program is configured to accept them. 

install from -c -m -g 0644 -o wheel -s jim to 
In the previous convoluted example, ‘from’ and ‘to’ are mandatory arguments, ‘-c’ and 
‘-s’ are true/false flags, ‘-m’ gets assigned ‘0644’, ‘-g’ gets ‘wheel’, and ‘-o’ gets ‘jim’. It 
would be much easier to write it as: 

install -cs -m 0644 -g wheel -o jim to from 

4.3 Long Versus Short Arguments 

Needs to be written. Sorry. 

4.4 Global Settings For All Argv Programs 

An environment variable is a variable that is part of the user’s working environment and 
is shared by all the programs. The ‘GL0BAL_ARGV’ variable is used by the argv library to 
customize its behavior at runtime. It can be set by hand and should probably be entered 
into your shell’s runtime configuration or RC file. 

To set the variable, C shell (csh or tcsh) users need to invoke: 

setenv GL0BAL_ARGV value 
Bourne shell (sh, bash, ksh, or zsh) users should use: 

GL0BAL_ARGV=value 
export GL0BAL_ARGV 

The value in the above example is a comma separated list of tokens each having a 
corresponding value. The tokens and their values are described below: 

• close - close argument acceptance 

Enables the handling of arguments such as ‘-m=444’ where ‘-m’ is a flag and ‘444’ is its 
value. 

Values: disable, enable. 

• disable - treat ‘=’ like a normal argument 

• enable (default) - enable the ‘-x=10’ format 

• env - environment variable handling 

Enables the processing of the ‘ARGV_*’ variables. If you have a set of options that you 
always use for ‘Is’ for instance, you cat set the ‘ARGV_LS’ environmental variable to 
hold these options. For instance: ‘setenv ARGV_LS "-sCF"’. 

Values: none, before, after. 
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• none - No processed at all 

• before (default) - options from env variable are processed Before command line 

• after - env options processed After command line 

• error - handling of usage errors 

Whenever you do not use a command correctly, this token determines how the library 
reports errors to you. 

Values: none, see, short, shortrem, long, all. 

• none - on errors print nothing but error message 

• see (default) - on errors print see -usage for more info. 

• short - on errors print the short-format usage messages 

• shortrem - on errors print short-format + how to get long 

• long - on errors print the long-format usage messages 

• all - on errors print the long-format usage messages + help, etc. 

• multi - the handling of arguments specified more than once 

If you use am argument twice on the command line, this token determines if the library 
should say it is an error. 

Values: accept, reject. 

• accept (default) - it’s NOT an error if specified more than once 

• reject - it’s an error if specified more than once 

• usage - usage messages for -usage 

Determines what messages the library prints when you use the ‘ — usage’ option. 

Values: short, shortrem, long, all. 

• short (default) - default is the short-format messages 

• shortrem - default is the short-format messages + how to get long 

• long - default is the long-format messages 

• all - default is the long-format messages + help, usage, version 
Examples: 

# accept -x=10, no env variables, long messages on errors, 

# accept multiple uses, and print all messages on — usage. 

setenv GLOBAL_ARGV close=accept ,env=none ,error=long,multi=accept ,usage=all( 

# process env variable options before command line, 

# and reject multiple argument uses 

setenv GLOBAL_ARGV env=before ,error=long,multi=reject 

4.5 Arguments For a Specific Argv Program 


Needs to be written. Sorry. 
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5 Plugs and Soapbox Comments 

Since I have your attention I would like to talk for a second about a couple of things 
that I feel strongly about. If you would like any more information about the below, please 
mail to the supplied addresses or drop me a line with any questions. 

The Electronic Frontier Foundation (EFF) 

The EFF is a organization committed to ensuring that the rules, regulations, 
and laws being applied to emerging communications technologies are in keeping 
with our society’s highest traditions of the free and open flow of ideas and 
information while protecting personal privacy. <eff@eff.org> 

Computer Professionals for Social Responsibility (CPSR) 

CPSR is a public-interest alliance of computer scientists and others interested 
in the impact of computer technology on society. We work to influence de- 
cisions regarding the development and use of computers because those deci- 
sions have far-reaching consequences and reflect basic values and priorities. 
CcpsrOcsli. Stanford. edu> 

Berkeley Software Design, Inc. (ESDI) 

I am a proud and enthusiastic owner and user of the BSDI-OS operating sys- 
tem. For ~$l+k you get a complete BSD-flavor operating system with full 
source for 386 and 486 systems (binary licenses are available). Along with the 
obvious benefits of full source code come excellent customer support /service 
and system features such as a MS-DOG runtime environment, complete tcp/ip 
networking facilities including nfs, full software development utilities, X, etc. 
<bsdi-info@bsdi.com> 
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